---
id: LATAM - Primitives-spec
title: "Ficha técnica"
handle: Pagamentos LATAM
description: "Pagamentos LATAM"
custom_edit_url: null
---
## Escopos necessários

O token para consumir esta API deve ser gerado usando o Authorization Code.

**O escopo `openid` é obrigatório. Ele permite consultar o perfil do usuário BTG com acesso à conta.**

É necessário incluir o seguinte escopo:

| Escopo                               | Descrição                                                        |
| :----------------------------------- | :--------------------------------------------------------------- |
| brn:btg:empresas:banking:collections | Permite a consulta e gestão de pagamentos, lotes e contas       |

## Ambiente de sandbox

Esta API está disponível **apenas no sandbox** (`api.sandbox.empresas.btgpactual.com`), um ambiente de testes para você construir e validar sua integração antes de operar com dados reais.

- Nada do que você faz aqui movimenta dinheiro de verdade.
- Tudo o que você cria pode ser consultado depois pelo `id` devolvido.
- Os dados de teste podem ser reiniciados periodicamente.
- Toda criação ou alteração deve enviar o header `X-Idempotency-Key`. Repetir a mesma chave devolve o mesmo resultado, sem duplicar a operação.

## O que você pode fazer

- **Pagamentos** e **comprovantes**: pague por Pix, TED, boleto, DARF e outros meios, e obtenha o comprovante de cada pagamento concluído.
- **Lotes**: reúna vários pagamentos e dispare todos de uma só vez.
- **Contas, saldo e extrato**: consulte as contas da empresa, o saldo disponível e as movimentações.

O `status` de cada recurso é definido pela plataforma e nunca é informado por você.

## Jornada de um pagamento

1. **Consulte suas contas e o saldo.** Identifique a conta de origem e confirme que há saldo disponível.
2. **Inicie o pagamento.** Informe o meio (por exemplo, Pix ou TED), o valor e os dados do favorecido. O pagamento nasce com um `id`.
3. **Aguarde a aprovação, se necessária.** Dependendo das regras da empresa, o pagamento fica em `pending_approval` até ser aprovado.
4. **Acompanhe o resultado.** Consulte o pagamento pelo `id` até que ele chegue a um estado final: `settled` (concluído), `failed` (recusado) ou `canceled` (cancelado por você).
5. **Obtenha o comprovante.** Para pagamentos concluídos, consulte o comprovante.
6. **Confira no extrato.** O pagamento aparece como débito nas movimentações da conta.

Enquanto o pagamento ainda não foi concluído, você pode cancelá-lo. Depois de `settled`, `failed` ou `canceled`, ele não aceita novas alterações, exceto a devolução de um pagamento já concluído.

## Jornada de um lote

1. **Abra um lote.** Ele começa vazio e tem prazo e capacidade máxima de pagamentos.
2. **Adicione pagamentos ao lote.** Ao iniciar cada pagamento, informe o `batchRef` do lote. Os pagamentos só são disparados quando o lote for processado.
3. **Processe o lote.** Todos os pagamentos são disparados de uma só vez. Se o lote exigir aprovação, uma única aprovação libera todos os itens.
4. **Acompanhe o andamento.** O lote mostra quantos pagamentos já foram concluídos e, ao final, fica totalmente concluído ou parcialmente falho.
5. **Abandone, se desistir.** Um lote ainda não processado pode ser descartado sem disparar nenhum pagamento.

## Como simular o andamento de um pagamento

No sandbox não há um banco real confirmando as operações. Para simular o que aconteceria em produção, use `POST /{companyId}/banking/primitives/_sandbox/advance`, informando o `resourceId` do pagamento e o `event` desejado:

| `event`            | Resultado no pagamento                  |
| :----------------- | :-------------------------------------- |
| `settle`           | Pagamento concluído (`settled`)         |
| `fail`             | Recusado pelo meio de pagamento (`failed`) |
| `require_approval` | Aguardando aprovação (`pending_approval`) |
| `approve`          | Aprovado (`approved`)                   |
| `revert`           | Devolvido depois de concluído           |

## Eventos de webhook

:::info Em breve
Os webhooks desta API **ainda não estão disponíveis**. Por enquanto, acompanhe o andamento dos pagamentos e lotes consultando-os pelo `id`.

Quando forem liberados, você poderá receber notificações automáticas sobre as mudanças de status, sem precisar consultar repetidamente. Esta página será atualizada com a lista de eventos e seus payloads.
:::